package com.kexio.user.service;

import java.util.List;

import com.kexio.auth.dto.LoginRequest;
import com.kexio.auth.dto.LoginResponse;
import com.kexio.common.dto.SessionInfo;
import com.kexio.user.dto.LogoutRequest;
import com.kexio.user.dto.RefreshTokenRequest;
import com.kexio.user.dto.UserDTO;

import jakarta.servlet.http.HttpServletRequest;

/**
 * 认证服务接口
 * 
 * 提供用户认证相关的核心业务逻辑，包括：
 * - 用户登录认证
 * - 令牌刷新
 * - 用户登出
 * - 用户信息获取
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface AuthService {
    
    /**
     * 用户登录
     * 
     * 验证用户凭据并生成访问令牌和刷新令牌
     * 
     * @param loginRequest 登录请求
     * @param request HTTP请求对象（用于获取IP、User-Agent等信息）
     * @return 登录响应，包含令牌和用户信息
     * @throws com.kexio.auth.exception.AuthenticationException 认证失败异常
     */
    LoginResponse login(LoginRequest loginRequest, HttpServletRequest request);
    
    /**
     * 刷新访问令牌
     * 
     * 使用刷新令牌生成新的访问令牌
     * 
     * @param refreshRequest 刷新令牌请求
     * @param request HTTP请求对象
     * @return 新的登录响应，包含新的访问令牌
     * @throws com.kexio.auth.exception.TokenException 令牌相关异常
     */
    LoginResponse refreshToken(RefreshTokenRequest refreshRequest, HttpServletRequest request);
    
    /**
     * 用户登出
     * 
     * 使令牌失效并清理相关会话信息
     * 
     * @param logoutRequest 登出请求
     * @param request HTTP请求对象
     * @return 是否登出成功
     */
    boolean logout(LogoutRequest logoutRequest, HttpServletRequest request);
    
    /**
     * 获取当前用户信息
     * 
     * 基于当前安全上下文返回用户详细信息
     * 
     * @return 用户资料响应
     * @throws com.kexio.auth.exception.UnauthorizedException 未认证异常
     */
    UserDTO getCurrentUserProfile();
    
    /**
     * 验证访问令牌
     * 
     * 检查访问令牌是否有效
     * 
     * @param accessToken 访问令牌
     * @param tenantId 租户ID
     * @return 是否有效
     */
    boolean validateAccessToken(String accessToken, String tenantId);
    
    /**
     * 验证刷新令牌
     * 
     * 检查刷新令牌是否有效
     * 
     * @param refreshToken 刷新令牌
     * @param tenantId 租户ID
     * @return 是否有效
     */
    boolean validateRefreshToken(String refreshToken, String tenantId);
    
    /**
     * 强制用户登出
     * 
     * 管理员强制指定用户登出所有设备
     * 
     * @param userId 用户ID
     * @param operatorId 操作者ID
     * @param reason 登出原因
     * @return 是否成功
     */
    boolean forceLogout(String userId,  String operatorId, String reason);
    
    /**
     * 批量强制用户登出
     * 
     * 管理员批量强制用户登出
     * 
     * @param userIds 用户ID列表
     * @param operatorId 操作者ID
     * @param reason 登出原因
     * @return 成功登出的用户数量
     */
    int batchForceLogout(java.util.List<String> userIds, String operatorId, String reason);
    
    /**
     * 获取租户活跃会话列表
     * @param tenantId 租户ID
     * @return 活跃会话列表
     */
    List<SessionInfo> getTenantActiveSessions(String tenantId);
    
    /**
     * 获取全局所有活跃会话列表（跨租户）
     * @return 所有租户的活跃会话列表
     */
    List<SessionInfo> getAllActiveSessions();
    
    /**
     * 检查用户是否在线
     * 
     * @param userId 用户ID
     * @return 是否在线
     */
    boolean isUserOnline(String userId);
    
    /**
     * 获取租户在线用户数量
     * 
     * @param tenantId 租户ID
     * @return 在线用户数量
     */
    long getOnlineUserCount(String tenantId);
    
    /**
     * 获取在线用户详细信息
     * 
     * @param tenantId 租户ID
     * @param includeDetails 是否包含详细信息
     * @return 在线用户详细信息
     */
    com.kexio.user.dto.OnlineUserDetailDTO getOnlineUserDetails(String tenantId, boolean includeDetails);
    
    /**
     * 获取全局在线用户数量
     *
     * @return 在线用户数量
     */
    Long getOnlineUserCount();
    
    /**
     * 刷新用户权限
     * 清除权限缓存，使权限变更立即生效
     * 
     * @param userId 用户ID
     * @return 是否成功
     */
    boolean refreshUserPermissions(String userId);
    
    /**
     * 用户注册
     * 
     * 创建新用户账号并完成初始化设置。
     * 注册成功后需要用户手动登录。
     * 
     * @param userDTO 用户注册信息（使用CreateGroup验证分组）
     * @param request HTTP请求对象（用于获取IP、User-Agent等信息）
     * @throws com.kexio.common.exception.BusinessException 注册失败异常
     */
    void register(UserDTO userDTO, HttpServletRequest request);
}
